RustSuggest.sys.mjs

class RustSuggest.sys.AlternateNames()

A set of names for a single entity.

RustSuggest.sys.AlternateNames.abbreviation: The entity’s abbreviation, if any.

RustSuggest.sys.AlternateNames.localized: The entity’s name in the language that was ingested according to the locale in the remote settings context. If none exists and this AlternateNames is for a Geoname, then this will be its primary name.

RustSuggest.sys.AlternateNames.primary: The entity’s primary name. For a Geoname, this is Geoname::name.

class RustSuggest.sys.Backoff(): The server requested a backoff after too many requests

class RustSuggest.sys.FtsMatchInfo()

Additional data about how an FTS match was made

RustSuggest.sys.FtsMatchInfo.prefix: Was this a prefix match (water b matched against water bottle)

RustSuggest.sys.FtsMatchInfo.stemming: Did the match require stemming? (run shoes matched against running shoes)

class RustSuggest.sys.Geoname()

A single geographic place.

This corresponds to a single row in the main “geoname” table described in the GeoNames documentation [1]. We exclude fields we don’t need.

[1]: https://download.geonames.org/export/dump/readme.txt

RustSuggest.sys.Geoname.adminDivisionCodes: Administrative divisions. This maps admin division levels (1-based) to their corresponding codes. For example, Liverpool has two admin divisions: “ENG” at level 1 and “H8” at level 2. They would be represented in this map with entries (1, “ENG”) and (2, “H8”).

RustSuggest.sys.Geoname.countryCode: ISO-3166 two-letter uppercase country code, e.g., “US”.

RustSuggest.sys.Geoname.featureClass

Primary geoname category. Examples:

“PCLI” - Independent political entity: country “A” - Administrative division: state, province, borough, district, etc. “P” - Populated place: city, village, etc.

RustSuggest.sys.Geoname.featureCode

Secondary geoname category, depends on feature_class. Examples:

“ADM1” - Administrative division 1 “PPL” - Populated place like a city

RustSuggest.sys.Geoname.geonameId: The geonameid straight from the geoname table.

RustSuggest.sys.Geoname.geonameType: The geoname type. This is derived from feature_class and feature_code as a more convenient representation of the type.

RustSuggest.sys.Geoname.latitude: Latitude in decimal degrees (as a string).

RustSuggest.sys.Geoname.longitude: Longitude in decimal degrees (as a string).

RustSuggest.sys.Geoname.name: The place’s primary name.

RustSuggest.sys.Geoname.population: Population size.

class RustSuggest.sys.GeonameAlternates()

Alternate names for a geoname and its country and admin divisions.

RustSuggest.sys.GeonameAlternates.adminDivisions: Names for the geoname’s admin divisions. This is parallel to Geoname::admin_division_codes. If there are no names in the ingested data for an admin division, then it will be absent from this map.

RustSuggest.sys.GeonameAlternates.country: Names for the geoname’s country. This will be Some as long as the country is also in the ingested data, which should typically be true.

RustSuggest.sys.GeonameAlternates.geoname: Names for the geoname itself.

class RustSuggest.sys.GeonameMatch()

A fetched geoname with info on how it was matched.

RustSuggest.sys.GeonameMatch.geoname: The geoname that was matched.

RustSuggest.sys.GeonameMatch.matchType: The type of name that was matched.

RustSuggest.sys.GeonameMatch.prefix: Whether the name was matched by prefix.

class RustSuggest.sys.GeonameType()

The type of a geoname.

RustSuggest.sys.GeonameType.AdminDivision

RustSuggest.sys.GeonameType.AdminDivisionOther

RustSuggest.sys.GeonameType.City

RustSuggest.sys.GeonameType.Country

RustSuggest.sys.GeonameType.Other

class RustSuggest.sys.InterruptKind()

What should be interrupted when [SuggestStore::interrupt] is called?

RustSuggest.sys.InterruptKind.READ: Interrupt read operations like [SuggestStore::query]

RustSuggest.sys.InterruptKind.READ_WRITE: Interrupt both read and write operations,

RustSuggest.sys.InterruptKind.WRITE: Interrupt write operations. This mostly means [SuggestStore::ingest], but other operations may also be interrupted.

class RustSuggest.sys.Interrupted(): An operation was interrupted by calling SuggestStore.interrupt()

class RustSuggest.sys.LabeledTimingSample()

Single sample for a Glean labeled_timing_distribution

RustSuggest.sys.LabeledTimingSample.label: label

RustSuggest.sys.LabeledTimingSample.value: Time in microseconds

class RustSuggest.sys.Network(): Network

class RustSuggest.sys.Other(): Other

class RustSuggest.sys.SuggestApiError(): The error type for all Suggest component operations. These errors are exposed to your application, which should handle them as needed.

class RustSuggest.sys.SuggestGlobalConfig()

Global Suggest configuration data.

RustSuggest.sys.SuggestGlobalConfig.showLessFrequentlyCap: showLessFrequentlyCap

class RustSuggest.sys.SuggestIngestionConstraints()

Constraints limit which suggestions to ingest from Remote Settings.

RustSuggest.sys.SuggestIngestionConstraints.emptyOnly: Only run ingestion if the table suggestions is empty

RustSuggest.sys.SuggestIngestionConstraints.providerConstraints: providerConstraints

RustSuggest.sys.SuggestIngestionConstraints.providers: providers

class RustSuggest.sys.SuggestIngestionMetrics()

Ingestion metrics

These are recorded during [crate::Store::ingest] and returned to the consumer to record.

RustSuggest.sys.SuggestIngestionMetrics.downloadTimes: Samples for the suggest.ingestion_download_time metric

RustSuggest.sys.SuggestIngestionMetrics.ingestionTimes: Samples for the suggest.ingestion_time metric

class RustSuggest.sys.SuggestProviderConfig()

Per-provider configuration data.

RustSuggest.sys.SuggestProviderConfig.Weather

class RustSuggest.sys.SuggestStore()

The store is the entry point to the Suggest component. It incrementally downloads suggestions from the Remote Settings service, stores them in a local database, and returns them in response to user queries.

Your application should create a single store, and manage it as a singleton. The store is thread-safe, and supports concurrent queries and ingests. We expect that your application will call [SuggestStore::query()] to show suggestions as the user types into the address bar, and periodically call [SuggestStore::ingest()] in the background to update the database with new suggestions from Remote Settings.

For responsiveness, we recommend always calling query() on a worker thread. When the user types new input into the address bar, call [SuggestStore::interrupt()] on the main thread to cancel the query for the old input, and unblock the worker thread for the new query.

The store keeps track of the state needed to support incremental ingestion, but doesn’t schedule the ingestion work itself, or decide how many suggestions to ingest at once. This is for two reasons:

1. The primitives for scheduling background work vary between platforms, and aren’t available to the lower-level Rust layer. You might use an idle timer on Desktop, WorkManager on Android, or BGTaskScheduler on iOS. 2. Ingestion constraints can change, depending on the platform and the needs of your application. A mobile device on a metered connection might want to request a small subset of the Suggest data and download the rest later, while a desktop on a fast link might download the entire dataset on the first launch.

RustSuggest.sys.SuggestStore.anyDismissedSuggestions(): Return whether any suggestions have been dismissed.

RustSuggest.sys.SuggestStore.clear(): Removes all content from the database.

RustSuggest.sys.SuggestStore.clearDismissedSuggestions(): Clear dismissed suggestions

RustSuggest.sys.SuggestStore.dismissByKey(key)

Dismiss a suggestion by its dismissal key.

Dismissed suggestions cannot be fetched again.

Prefer [SuggestStore::dismiss_by_suggestion] if you have a crate::Suggestion. This method is intended for cases where a suggestion originates outside this component.

RustSuggest.sys.SuggestStore.dismissBySuggestion(suggestion)

Dismiss a suggestion.

Dismissed suggestions cannot be fetched again.

RustSuggest.sys.SuggestStore.dismissSuggestion(suggestionUrl)

Deprecated, use [SuggestStore::dismiss_by_suggestion] or [SuggestStore::dismiss_by_key] instead.

Dismiss a suggestion

Dismissed suggestions will not be returned again

RustSuggest.sys.SuggestStore.fetchGeonameAlternates(geoname)

Fetches a geoname’s names stored in the database.

See fetch_geoname_alternates in geoname.rs for documentation.

RustSuggest.sys.SuggestStore.fetchGeonames(query, matchNamePrefix, filter)

Fetches geonames stored in the database. A geoname represents a geographic place.

See fetch_geonames in geoname.rs for documentation.

RustSuggest.sys.SuggestStore.fetchGlobalConfig(): Returns global Suggest configuration data.

RustSuggest.sys.SuggestStore.fetchProviderConfig(provider): Returns per-provider Suggest configuration data.

RustSuggest.sys.SuggestStore.ingest(constraints): Ingests new suggestions from Remote Settings.

RustSuggest.sys.SuggestStore.interrupt(kind)

Interrupts any ongoing queries.

This should be called when the user types new input into the address bar, to ensure that they see fresh suggestions as they type. This method does not interrupt any ongoing ingests.

RustSuggest.sys.SuggestStore.isDismissedByKey(key)

Return whether a suggestion has been dismissed given its dismissal key.

[SuggestStore::query] will never return dismissed suggestions, so normally you never need to know whether a suggestion has been dismissed. This method is intended for cases where a dismissal key originates outside this component.

RustSuggest.sys.SuggestStore.isDismissedBySuggestion(suggestion)

Return whether a suggestion has been dismissed.

[SuggestStore::query] will never return dismissed suggestions, so normally you never need to know whether a Suggestion has been dismissed, but this method can be used to do so.

RustSuggest.sys.SuggestStore.query(query): Queries the database for suggestions.

RustSuggest.sys.SuggestStore.queryWithMetrics(query): Queries the database for suggestions.

class RustSuggest.sys.SuggestStoreBuilder()

Builder for [SuggestStore]

Using a builder is preferred to calling the constructor directly since it’s harder to confuse the data_path and cache_path strings.

RustSuggest.sys.SuggestStoreBuilder.build(): build

RustSuggest.sys.SuggestStoreBuilder.cachePath(path): Deprecated: this is no longer used by the suggest component.

RustSuggest.sys.SuggestStoreBuilder.dataPath(path): dataPath

RustSuggest.sys.SuggestStoreBuilder.loadExtension(library, entryPoint)

Add an sqlite3 extension to load

library_name should be the name of the library without any extension, for example libmozsqlite3. entrypoint should be the entry point, for example sqlite3_fts5_init. If null (the default) entry point will be used (see https://sqlite.org/loadext.html for details).

RustSuggest.sys.SuggestStoreBuilder.remoteSettingsBucketName(bucketName): remoteSettingsBucketName

RustSuggest.sys.SuggestStoreBuilder.remoteSettingsServer(server): remoteSettingsServer

RustSuggest.sys.SuggestStoreBuilder.remoteSettingsService(rsService): remoteSettingsService

class RustSuggest.sys.Suggestion()

A suggestion from the database to show in the address bar.

RustSuggest.sys.Suggestion.Amo

RustSuggest.sys.Suggestion.Amp

RustSuggest.sys.Suggestion.Dynamic

RustSuggest.sys.Suggestion.Fakespot

RustSuggest.sys.Suggestion.Mdn

RustSuggest.sys.Suggestion.Pocket

RustSuggest.sys.Suggestion.Weather

RustSuggest.sys.Suggestion.Wikipedia

RustSuggest.sys.Suggestion.Yelp

class RustSuggest.sys.SuggestionProvider()

A provider is a source of search suggestions.

RustSuggest.sys.SuggestionProvider.AMO: AMO

RustSuggest.sys.SuggestionProvider.AMP: AMP

RustSuggest.sys.SuggestionProvider.DYNAMIC: DYNAMIC

RustSuggest.sys.SuggestionProvider.FAKESPOT: FAKESPOT

RustSuggest.sys.SuggestionProvider.MDN: MDN

RustSuggest.sys.SuggestionProvider.POCKET: POCKET

RustSuggest.sys.SuggestionProvider.WEATHER: WEATHER

RustSuggest.sys.SuggestionProvider.WIKIPEDIA: WIKIPEDIA

RustSuggest.sys.SuggestionProvider.YELP: YELP

class RustSuggest.sys.SuggestionProviderConstraints()

Some providers manage multiple suggestion subtypes. Queries, ingests, and other operations on those providers must be constrained to a desired subtype.

RustSuggest.sys.SuggestionProviderConstraints.ampAlternativeMatching: Which strategy should we use for the AMP queries? Use None for the default strategy.

RustSuggest.sys.SuggestionProviderConstraints.dynamicSuggestionTypes: Which dynamic suggestions should we fetch or ingest? Corresponds to the suggestion_type value in dynamic suggestions remote settings records.

class RustSuggest.sys.SuggestionQuery()

A query for suggestions to show in the address bar.

RustSuggest.sys.SuggestionQuery.keyword: keyword

RustSuggest.sys.SuggestionQuery.limit: limit

RustSuggest.sys.SuggestionQuery.providerConstraints: providerConstraints

RustSuggest.sys.SuggestionQuery.providers: providers

class RustSuggest.sys.YelpSubjectType()

Subject type for Yelp suggestion.

RustSuggest.sys.YelpSubjectType.BUSINESS: BUSINESS

RustSuggest.sys.YelpSubjectType.SERVICE: SERVICE

RustSuggest.sys.rawSuggestionUrlMatches(rawUrl, cookedUrl): Determines whether a “raw” sponsored suggestion URL is equivalent to a “cooked” URL. The two URLs are equivalent if they are identical except for their replaced template parameters, which can be different.